Inside Macintosh: QuickTime
The Movie Toolbox provides a set of high-level functions that allow you to edit movies. This section describes these high-level editing functions. These functions work with a movie's current selection. The current selection is defined by a starting time and a duration.
The Movie Toolbox also provides functions that allow you to edit movie segments. Those functions are described in "Low-Level Movie-Editing Functions," .
The movies created by these functions contain references to the data in the source movie. Because the new movies contain references and not data, they are small and easily moved to and from the scrap. If you delete the movie that contains the data, the data references in the new movies are no longer valid and the new movies cannot be played. Therefore, before you delete the original movie, you should call the FlattenMovie function (described on FlattenMovie ) for each of the new movies. This function copies the data into each of the new movies, eliminating the data references.
Note that the Movie Toolbox does not always copy empty tracks from the source movie to the movies that are created by these functions. Specifically, the Movie Toolbox preserves the empty tracks until you paste or add the selection into the destination movie. At that time, the Movie Toolbox removes the empty tracks from the selection. In addition, if a track in the source movie has trailing empty space, the Movie Toolbox removes that empty space from the track when it is copied into the new movie. Therefore, if you want to add a segment beyond the end of a movie, you insert the space when you insert the new segment using the InsertMovieSegment function (described on InsertMovieSegment ).
The Movie Toolbox allows you to paste different data types into a movie. For example, QuickDraw pictures and standard sound data can be pasted directly into a movie. If you are using the movie controller component, you do not need to use these functions to paste different data types into a movie. (For details on the movie controller component, see Inside Macintosh: QuickTime Components .) If you are calling the Movie Toolbox directly to do editing, you should use the functions described in this section.
To get and change a movie's current selection, your application can call the GetMovieSelection and SetMovieSelection functions.
Your application can work with a movie's current selection by calling the CutMovieSelection , CopyMovieSelection , PasteMovieSelection , ClearMovieSelection , and AddMovieSelection functions.
The PutMovieOnScrap and NewMovieFromScrap functions enable your application to work with movies that are on the scrap.
The IsScrapMovie function examines the system scrap to determine whether it can translate any of the data into a movie. The PasteHandleIntoMovie takes the contents of a specified handle, together with its type, and pastes it into a movie. PutMovieIntoTypedHandle takes a movie (or a single track from within a movie) and converts it into a handle.
The PutMovieOnScrap function allows your application to place a movie onto the scrap.
pascal OSErr PutMovieOnScrap (Movie theMovie,
long movieScrapFlags);
The NewMovieFromScrap function allows your application to create a movie from the contents of the scrap, if this is possible. If there is no movie data on the scrap, the Movie Toolbox does not create a new movie.
pascal Movie NewMovieFromScrap (long newMovieFlags);
The SetMovieSelection function sets a movie's current selection.
pascal void SetMovieSelection (Movie theMovie,
TimeValue selectionTime,
TimeValue selectionDuration);
If you set the selectionDuration parameter to a value greater than the movie's duration, SetMovieSelection automatically adjusts the duration of the selection to correspond to the difference between the value specified in the selectionTime parameter and the end of the movie.
The GetMovieSelection function returns information about a movie's current selection.
pascal void GetMovieSelection (Movie theMovie,
TimeValue *selectionTime,
TimeValue *selectionDuration);
The CutMovieSelection function creates a new movie that contains the original movie's current selection. This function then removes the current selection from the original movie. After the current selection has been removed from the original movie, the duration of the current selection is 0. The starting time of the current selection is not affected.
pascal Movie CutMovieSelection (Movie theMovie);
The CutMovieSelection function returns a movie identifier. If the function could not create the new movie, it sets this returned identifier to nil .
Your application must dispose of the new movie once you are done with it. You can use the DisposeMovie function (described on DisposeMovie ) to dispose of the new movie.
If you have assigned a progress function to the source movie, the Movie Toolbox calls that progress function during long cut operations. (For details on progress functions, see "Progress Functions," .)
The CopyMovieSelection function creates a new movie that contains the original movie's current selection. This function does not change the original movie or the current selection.
pascal Movie CopyMovieSelection (Movie theMovie);
The CopyMovieSelection function returns a movie identifier. If the function could not create the new movie, it sets this returned identifier to nil .
Your application must dispose of the new movie once you are done with it. You can use the DisposeMovie function (described on DisposeMovie ) to dispose of the new movie.
If you have assigned a progress function to the source movie, the Movie Toolbox calls that progress function during long copy operations. (For details on progress functions, see "Progress Functions," .)
The PasteMovieSelection function places the tracks from one movie into another movie.
pascal void PasteMovieSelection (Movie theMovie, Movie src);
All of the tracks from the source movie are placed in the destination movie. If the duration of the destination movie's current selection is 0, the source movie is inserted at the starting time of the current selection. If the current selection duration is nonzero, the function clears the current selection and then inserts the tracks from the source movie. After the paste operation, the current selection time is unchanged, and the selection duration is set to the source movie's duration.
Whenever possible, the Movie Toolbox uses existing tracks to store the data to be pasted. Before adding a track to the destination movie, the toolbox looks in the destination movie for tracks that have the same characteristics as the tracks in the source movie. The toolbox considers the following characteristics when searching for an appropriate track:
If the Movie Toolbox cannot find an appropriate track in the destination movie, it creates a track with the proper characteristics.
The Movie Toolbox removes any empty tracks from the destination movie after the paste operation.
If you have assigned a progress function to the destination movie, the Movie Toolbox calls that progress function during long paste operations. (For details on progress functions, see "Progress Functions," .)
The entire source movie is used regardless of the selection in the source movie.
If you want to insert only a part of the source movie, use the InsertMovieSegment function, which is described on InsertMovieSegment .
The AddMovieSelection function adds one or more tracks to a movie. This function scales the source movie so that it fits into the destination selection. If the current selection in the destination movie has a 0 duration, the Movie Toolbox adds the segment at the beginning of the current selection.
pascal void AddMovieSelection (Movie theMovie, Movie src);
The AddMovieSelection function is similar to PasteMovieSelection , which is described in the previous section. However, the PasteMovieSelection function inserts empty space into a movie's existing tracks and then adds the new track data. The AddMovieSelection function does not insert empty space into the existing tracks. This function simply adds the tracks in parallel from the source movie to the destination movie. This can be useful for adding a track to an existing movie, such as adding sound to a silent movie.
The Movie Toolbox removes any empty tracks from the destination movie after the add operation.
If you have assigned a progress function to the destination movie, the Movie Toolbox calls that progress function during long add operations. (For details, see "Progress Functions," .)
The entire source movie is used regardless of the selection in the source movie.
The ClearMovieSelection function removes the segment of the movie that is defined by the current selection.
pascal void ClearMovieSelection (Movie theMovie);
The IsScrapMovie function looks on the system scrap to find out if it can translate any of the data into a movie.
pascal Component IsScrapMovie (Track targetTrack);
The PasteHandleIntoMovie function takes the contents of a specified handle, together with its type, and pastes it into a specified movie.
pascal OSErr PasteHandleIntoMovie (Handle h, OSType handleType,
Movie theMovie, long flags,
ComponentInstance userComp);
If the handle is set to 0, PasteHandleIntoMovie searches the scrap for a field of the type handleType . If both the h parameter and the handleType parameter are nil , PasteHandleIntoMovie uses the first available data from the scrap.
If you are just pasting in data from the scrap, it is best to allow PasteHandleIntoMovie to retrieve the data from the scrap, rather than doing it yourself. In this way, the function is able to obtain supplemental data from the scrap, if necessary (for example, 'styl' resources for 'TEXT' ).
PasteHandleIntoMovie pastes into the current selection according to the following rules:
The PutMovieIntoTypedHandle function takes a movie (or a single track from within that movie) and converts it into a handle of a specified type.
pascal OSErr PutMovieIntoTypedHandle (Movie theMovie,
Track targetTrack,
OSType handleType,
Handle publicMovie,
TimeValue start,
TimeValue dur,
long flags,
ComponentInstance userComp);